Contributor CLI: route and expectation ports, probe runner, scaffolding - #1

Dependency-free Node 22 scripts for contributors, with tests, wired into CI and the docs.

What is here

• scripts/lib/routes.mjs: port of OAuthProvider.path_allowed?/3, AccessPolicy.path_matches_any?/2 and Connector.safe_path?/1 (exact, prefix *, :name segments with reserved literals, trailing * after parameters, path_param with the \A/\z anchors translated for JS).
• scripts/lib/expect.mjs: port of Connector.Expect plus the manifest's [path, check, ...args] decoding and validation.
• v1/vectors.json is the parity contract. Its route, expectation and malformed-expectation cases come from sprites-api's oauth_provider_routes_test.exs and expect_test.exs, plus cases for the rules those tests do not spell out (prefix patterns, null method, deep fan-out, per-element absence). The JS tests run every vector; sprites-api should run the same file (not changed in this PR).
• scripts/check-connectors.mjs also asserts: the probe path (query stripped) is allowed for its method, every example path is allowed for its method, every expect in the probe and its errors rules is well-formed, and path_param compiles. Existing checks kept. Shared logic lives in scripts/lib/manifest.mjs so the tests can run it on the template too.
• scripts/probe.mjs <name> --key-env VAR [--write-fixture]: builds the request as the gateway does (bearer or header auth with optional prefix, test_request_headers or the content-type default for JSON bodies, user-agent: Sprites-API-Gateway, no redirects, no retries, receive_timeout default 10 s), prints each assertion, classifies non-200 responses with the errors rules then the 401 default, and writes connectors/<name>/fixtures/probe_<status>.json after redaction. The key is never printed.
• scripts/new.mjs <name>: copies the template, sets name and display_name, refuses an existing directory or an invalid name.
• CI runs node --test "scripts/test/*.test.mjs" and validates the template with ajv as well. CONTRIBUTING.md's Checks section and README.md's layout block are updated.
• The template's probe GET /v1/me was not in its own allowed_paths; the new check caught it and the template now lists it.

Layout

Two roots, same per-connector layout:

• connectors/ holds community connectors only. sprites-api vendors every directory here at a tag of this repository and fails its build on a name that collides with a built-in provider, so the eleven seeds cannot live here. It currently holds only a README saying so.
• examples/ holds the eleven first-party connectors (exports of production) as worked examples and as fixtures for the tests. One moves to connectors/ only deliberately, together with the removal of its Elixir module in sprites-api.

check-connectors.mjs checks both roots by default and finds a named connector in either; probe.mjs resolves connectors/<name> then examples/<name>; new.mjs always creates under connectors/. The ajv step validates examples/ and the template, and connectors/ only when it has a manifest, because ajv exits non-zero on a glob with no matches.

Probe recordings live at the repository root in fixtures/<name>/probe_<status>.json, never inside a connector directory: a release imports only the four connector files, so check-connectors.mjs refuses anything else inside a connector and validates fixtures/ (directories named after existing connectors, only probe_<status>.json files, valid JSON).

Semantics I was unsure about

1. safe_path? only guards :name routes. In sprites-api an exact or prefix * pattern goes through AccessPolicy and is not safe-path checked, so /v1/* forwards /v1/../x. The port and a vector reproduce that. If the gateway should refuse it, change sprites-api first and flip the vector.
2. Probe path in allowed_paths is a convention, not a gateway rule. The gateway sends the probe directly, so a probe outside allowed_paths works in production. All eleven connectors list theirs, and the check requires it as the task asked.
3. integer and float-integer ambiguity. Elixir decodes 1.0 as a float, JSON.parse cannot tell it from 1, so ["n", "integer"] on 1.0 passes here and fails in the gateway. Likewise in uses strict equality in Elixir (1 in [1.0] is false) but == elsewhere. The vectors avoid integral floats and say so in the header.
4. Legacy .* suffix. AccessPolicy treats a pattern ending in .* as a prefix with backslashes stripped. Ported and covered by a vector; the schema allows the spelling, though no connector uses it.
5. Non-JSON 200 bodies. Req decodes JSON by content-type; the probe runner does the same (json content-type only) and reports that a text body cannot satisfy any expectation.
6. Missing expect with hooks. A manifest whose probe relies on a hook's probe_ok?/1 cannot be judged here; the runner reports that and exits non-zero rather than passing a bare 200.
7. node --test scripts/test/ does not recurse into a directory on Node 22, so CI uses the glob form.

🤖 Generated with Claude Code